cs-security-experience-api-services

This section provides the meaning of the attributes included in the API.

💂️ Base Information

• API Title: Experience Security API Service
• Version: v2
• Base URL: https://security-experience-api-{env}.us-e1.cloudhub.io/api/Replace {env} with:
  • dev (Development)
  • qa (Quality Assurance)
  • prod (Production)

🔑 API KEYS

• "Authorization": "Bearer {{API_KEY}}"Attribute defined in the request header.

  • Type: String
  • Length: Minimum 36 characters, maximum 37 characters
  • Description: Authentication token required to access the API.

• "client_id": "{{CLIENT_ID}}"Attribute defined in the request header.

  • Type: String
  • Length: Minimum 32 characters, maximum 36 characters
  • Description: Unique client identifier used to authenticate the request.

NOTE: These API KEYS must be provided in every request to successfully access the services.

✨ Validate Identity (POST /customer/v1/identity/validate)

• Display Name: Validate Identity
• Description: Allows you to validate the identification data of the person to authenticate.
• Method: POST
• Request Body Attributes:
  • idUsuarioEntidad
    • Type: String
    • Description: (Optional) Connection user in Base64 format.
  • paramProducto
    • Type: String
    • Description: Parameter used for the validation process. (Required)
  • producto
    • Type: String
    • Description: Product code to use (e.g., "010" for Evidente Master). (Required)
  • canal
    • Type: String
    • Description: Access channel (e.g., "Fijo 001"). (Required)
  • datosValidacion (Object)
    • identificacion (Object):
      • Numero
        • Type: String
        • Description: Identification number. (Required)
      • Tipo
        • Type: String
        • Description: Type of identification (e.g., "1" for Cédula de Ciudadanía, "4" for Cédula de Extranjería). (Required)
    • primerApellido
      • Type: String
      • Max Length: 16 characters
      • Description: First surname from the identification document. (Required)
    • nombres
      • Type: String
      • Max Length: 40 characters
      • Description: One or two given names as per the document. (Required)
    • fechaExpedicion/timestamp
      • Type: String
      • Description: Date of issuance of the identification in timestamp format (milliseconds since January 1, 1970). (Required)
• Response Body Attributes:
  • RespValidacion (Object) containing:
    • valApellido
      • Type: Boolean
      • Description: Indicates if the validation of the first surname was successful.
    • valNombre
      • Type: Boolean
      • Description: Indicates if the validation of the given name was successful.
    • valFechaExp
      • Type: Boolean
      • Description: Indicates if the issuance date validation was successful.
    • excluirCliente
      • Type: Boolean
      • Description: Determines whether the client should be excluded based on alerts.
    • alertas
      • Type: Boolean
      • Description: Indicates whether there are alerts for the client.
    • respuestaAlerta
      • Type: String
      • Description: Code for the alert validation result. (Optional)
    • codigoAlerta
      • Type: String
      • Description: Alert code as per system table. (Optional)
    • resultado
      • Type: String
      • Description: Overall result code of the validation process.
    • regValidacion
      • Type: String
      • Description: Unique validation record number used for subsequent operations.
    • numIntentos
      • Type: Number
      • Description: Number of validation attempts made. (Optional)
    • resultadoProceso
      • Type: Boolean
      • Description: Indicates whether the validation process was executed successfully.
    • consultasDisponibles
      • Type: Number
      • Description: Available queries remaining for the identification. (Optional)
    • subTipoValidacion
      • Type: String
      • Description: Possible values for failed validations based on configuration. (Optional)
    • Identificacion (Object):
      • numero (String, Required)
      • tipo (String, Required)
    • Nombre
      • Type: String
      • Description: Full name of the validated person. (Optional)
    • FechaExpedicion/timestamp
      • Type: String
      • Description: Actual issuance date in timestamp format. (Required)

🔒 Initialize OTP (POST /security/v1/OTP/initialize)

• Display Name: Initialize OTP
• Description: Initializes an OTP transaction associated with Evidente Master.
• Method: POST
• Request Body Attributes:
  • idUsuarioEntidad
    • Type: String
    • Description: (Optional) Connection user in Base64 format.
  • iniciarTransaccionOTPSolicitud (Object) containing:
    • codParametrizacion
      • Type: String
      • Description: Code of the parametrization used to generate the OTP survey. (Required)
    • Identificacion (Object):
      • numero
        • Type: String
        • Description: Identification number. (Required)
      • tipo
        • Type: String
        • Description: Identification type. (Required)
    • datosCuestionario (Object):
      • regValidacion
        • Type: String
        • Description: Validation record number from the validate identity endpoint. (Required)
      • procesoEvidente
        • Type: String
        • Description: Process associated with Evidente (e.g., "VALDCN – Post validación"). (Required)
• Response Body Attributes:
  • IniciarTransaccionOTPRespuesta (Object) containing:
    • codParametrizacion
      • Type: String
    • DatosCuestionario (Object):
      • procesoEvidente
        • Type: String
      • regValidacion
        • Type: String
    • ResultadoGeneracion (Object):
      • codResultadoOTP
        • Type: String
        • Description: OTP result code as defined in the OTP result table.
      • idTransaccionOTP
        • Type: UUID
        • Description: Unique identifier for the OTP transaction.
      • resultadoOTP
        • Type: Boolean
        • Description: Flag confirming successful execution of the OTP process.

🔐 Validate OTP Code (POST /security/v1/OTP/validate)

• Display Name: Validate OTP Code
• Description: Verifies that the OTP code received by the user matches the code for the current identity verification transaction.
• Method: POST
• Request Body Attributes:
  • idUsuarioEntidad
    • Type: String
    • Description: (Optional) Connection user in Base64 format.
  • verificarCodigoOTPSolicitud (Object) containing:
    • idTransaccionOTP
      • Type: UUID
      • Description: Unique OTP transaction identifier. (Required)
    • codigoOTP
      • Type: String
      • Description: OTP code provided by the user (6 digits or "000000" for forced closure). (Required)
• Response Body Attributes:
  • resultadoVerificacionOTP
    • Type: Boolean
    • Description: Indicates whether the OTP code was validated successfully.
  • mensaje
    • Type: String
    • Description: Additional details about the OTP validation outcome. (Optional)

📝 Generate Survey (POST /security/v1/survey/generate)

• Display Name: Generate Survey
• Description: Generates a survey (questionnaire) to further verify an identification.
• Method: POST
• Request Body:
  • Type: definitions.generate-survey-request
  • (Refer to example: v1/examples/request/GenerateSurveyRequestExample.json)
• Response Body:
  • Type: definitions.generate-survey-response
  • (Refer to example: v1/examples/response/GenerateSurveyResponseExample.json)

📝 Validate Survey (POST /security/v1/survey/validate)

• Display Name: Validate Survey
• Description: Evaluates the responses to the generated survey for identity verification.
• Method: POST
• Request Body:
  • Type: definitions.validate-survey-request
  • (Refer to example: v1/examples/request/ValidateSurveyRequestExample.json)
• Response Body:
  • Type: definitions.validate-survey-response
  • (Refer to example: v1/examples/response/ValidateSurveyResponseExample.json)

🔑 Generate Token for PQR's (POST /security/v1/portal/generate_token)

• Display Name: Generate Token PQR's
• Description: Generates a token to access the PQR's form.
• Method: POST
• Request Body:
  • Type: definitions.generate-token-portal-request
  • (Refer to example: v1/examples/request/GenerateTokenPortalRequestExample.json)
• Response Body:
  • Type: definitions.generate-token-portal-response
  • (Refer to example: v1/examples/response/GenerateTokenPortalResponseExample.json)

🔑 Validate Token for PQR's (POST /security/v1/portal/validate_token)

• Display Name: Validate Token PQR's
• Description: Validates the token provided for accessing the PQR's form.
• Method: POST
• Request Body:
  • Type: definitions.validate-token-portal-request
  • (Refer to example: v1/examples/request/ValidateTokenPortalRequestExample.json)
• Response Body:
  • Type: definitions.validate-token-portal-response
  • (Refer to example: v1/examples/response/ValidateTokenPortalResponseExample.json)

⚙️ Check Blocking Lists (POST /security/v1/check_bls)

• Display Name: Check BLS
• Description: Checks the blocking lists to determine if an applicant should be rejected.
• Method: POST
• Request Body:
  • Type: definitions.check-bls-request
  • (Refer to example: v1/examples/request/CheckBLSRequestExample.json)
• Response Body:
  • Type: definitions.check-bls-response
  • (Refer to example: v1/examples/response/CheckBLSResponseExample.json)

📊 Common Parameters

🔒 Security Schemes

Client ID Enforcement

OAuth 2.0

⚠️ Common Error Codes

📞 Support

For any questions or issues, please contact the API support team INTEGRATION SERVICES AND APPLICATIONS COORDINATION.

Notes

• Documentation adjusted in February 2025.
• For additional information, contact: epalma@fgs.co